/*
 * Copyright 2009 XueSong Guo.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 * http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package cn.webwheel;

import java.util.List;
import java.util.Map;

/**
 * WebWheel MVC框架的过滤器组接口。<br>
 * 每个过滤器组可含有任意多的过滤器形成过滤器队列，每个过滤器组可绑定任意多的http请求地址到相应的动作类，
 * 当其中某个http请求被框架检测到时，框架将依次执行过滤器组中的过滤器队列，并最终抵达相应的动作类。<br>
 * 此接口的实现为不变的（immutable）对象，获得新过滤器组的方法只有使用{@link #append(Filter)}方法。
 */
public interface FilterGroup {

    /**
     * 追加新的过滤器，并返回追加后的过滤器组，当前的过滤器组不会改变。
     * @param filter 新的过滤器
     * @return 新的过滤器组
     */
    FilterGroup append(Filter filter);

    /**
     * 绑定http请求地址到动作类类型。<br>
     * http请求地址为对应于web应用程序的绝对路径，
     * 例如“/index.html”、“/some/dir/act”、“/some/dir/do.action”等等。
     * @param path http请求地址
     * @param actionClass 动作类类型
     */
    void bindAction(String path, Class<? extends Action> actionClass);

    /**
     * 获得不可更改的过滤器队列。
     * @return 过滤器队列
     */
    List<Filter> getFilters();

    /**
     * 获得此过滤器组所覆盖的所有动作类绑定，包括子过滤器组中绑定的动作类映射。
     * @return 动作类映射
     */
    Map<String, Class<? extends Action>> getActions();

    /**
     * 获得父过滤器组。
     * @return 父过滤器组
     */
    FilterGroup getParent();

    /**
     * 获得子过滤器组，也就是通过{@link #append(Filter)}方法所创建的所有子过滤器组。
     * @return 子过滤器组
     */
    List<? extends FilterGroup> getChildren();
}
